Fixing Invalid Git Paths on Windows

One of the fun things about working with Git on Windows is that you’re often at the mercy of the filesystem underneath you, and this crops up in some entertaining ways:

Even in the age of running Linux on Windows, these compatibility issues are not going away any time soon, and taking a repository and running it on Windows can be problematic, so the rest of this post is about repairing these repositories so they are not tied to a particular filesystem.

You might have stumbled upon an error like this when cloning down someone else’s repository:

So here is where Git is actually falling over:

Did you read the link above about valid file path characters? I’ll quote the relevant part here:

Use any character in the current code page for a name, including Unicode characters and characters in the extended character set (128–255), except for the following:

The following reserved characters:

(greater than)

…

So we can’t use \ as a path in Windows, but we have a repository that has some existing content using this character. That’s what we need to fix here.

At this point you could look inside the newly created repository on disk and try to salvage things. I wouldn’t recommend this approach because of this error message further down.

The working tree is the files on disk associated with the current branch (either the default branch or whatever branch you wanted to initially checkout). And with that in an unknown state, there is only pain ahead. Let’s try a different way.

Because git clone fails I used this set of commands to emulate a clone operation:

This gets us to a usable repository state, but these problem files still need addressing:

I’m going to just remove those so I have something to work with:

Now we have no problems checking out this branch, but we did this by removing the problem paths from the repository. If we want to be able to access those files in the repository we have more work to do.

Git keeps a history of all the file contents for all commits in it’s .git folder, and we can explore this using various Git plumbing commands.

We can use git ls-tree to read the tree contents of a given hash and find the original contents of the files we just removed:

Git stores each commit as a tree, and a tree can contain blobs (the file contents) or other trees. Each entry in a tree also needs a mode (for representing permissions) and a path. If you squint at this, it’s not unlike a filesystem representation as a data structure.

The two problem file paths are under test-files so we’ll use the e2a3b7648b57746e68ced4f881f193df05a2341f hash from the previous command and run git ls-tree again:

Excellent, we can see the problem file paths and they correlate to two blobs 5020200c10e545c19002f4878c2b6686035f10b0 and 0680d8432628eb071aa2c643f11fe8984df6e972. These identifiers can be used to find the file contents.

The next step is to read out the contents of those blobs and write them to new files. I’m going to also create the SavedData directory name again because I think that was the intent here and someone just used the wrong slash and got away with it.

Now we have two new files to commit:

I’m not worried about the line ending warning here, and I can confirm this is accurate once we’ve completed these steps.

Now we can commit these files to the new path:

Now we have a branch that can be cloned on Windows safely.

To confirm that line ending warning was a non-issue, I can run the same git ls-tree command from earlier and confirm the new blobs are unchanged:

The two files are at the expected new location but still have the old blob hash.

To confirm the clone has been fixed, I cloned down my fork and ask it to checkout this branch:

Now, you just need to merge this branch into the default branch and everyone will benefit from this change.